home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / lisp / stk-3.0 / stk-3 / blt-for-STk-3.0 / blt-1.9 / man / watch.man < prev    next >
Encoding:
Text File  |  1995-07-01  |  4.5 KB  |  129 lines
  1. '\"
  2. '\" Copyright 1994 by AT&T Bell Laboratories.
  3. '\"
  4. '\" Permission to use, copy, modify, and distribute this software
  5. '\" and its documentation for any purpose and without fee is hereby
  6. '\" granted, provided that the above copyright notice appear in all
  7. '\" copies and that both that the copyright notice and warranty
  8. '\" disclaimer appear in supporting documentation, and that the
  9. '\" names of AT&T Bell Laboratories any of their entities not be used
  10. '\" in advertising or publicity pertaining to distribution of the
  11. '\" software without specific, written prior permission.
  12. '\"
  13. '\" AT&T disclaims all warranties with regard to this software, including
  14. '\" all implied warranties of merchantability and fitness.  In no event
  15. '\" shall AT&T be liable for any special, indirect or consequential
  16. '\" damages or any damages whatsoever resulting from loss of use, data
  17. '\" or profits, whether in an action of contract, negligence or other
  18. '\" tortuous action, arising out of or in connection with the use or
  19. '\" performance of this software.
  20. '\"
  21. '\"
  22. .so man.macros
  23. .HS blt_watch cmds
  24. .BS
  25. .SH NAME
  26. blt_watch \- call Tcl procedures before and after each command
  27. .SH SYNOPSIS
  28. \fBblt_watch create\fR \fIname\fR ?\fIoptions\fR?
  29. .sp
  30. \fBblt_watch activate\fR \fIname\fR
  31. .sp
  32. \fBblt_watch deactivate\fR \fIname\fR
  33. .sp
  34. \fBblt_watch delete\fR \fIname\fR
  35. .sp
  36. \fBblt_watch configure\fR \fIname\fR ?\fIoptions\fR
  37. .sp
  38. \fBblt_watch info\fR \fIname\fR
  39. .sp
  40. \fBblt_watch names\fR 
  41. .BE
  42. .SH DESCRIPTION
  43. .PP
  44. This command arranges for Tcl procedures to be called before 
  45. and/or after each the execution of each Tcl command.  This command
  46. may be useful in the logging, profiling, or tracing of Tcl code.
  47. .SH "WATCH COMMANDS"
  48. The following commands are available for the \fBblt_watch\fR:
  49. .TP
  50. \fBblt_watch activate \fIname\fR 
  51. Activates the watch, causing Tcl commands the be traced to the
  52. maximum depth selected.
  53. .TP
  54. \fBblt_watch create \fIname\fR ?\fIoptions\fR?...
  55. Creates a new watch \fIname\fR. It's an error if another watch 
  56. \fIname\fR already exists and an error message will be returned.
  57. \fIOptions\fR may have any of the values accepted by the 
  58. \fBblt_watch configure\fR command.
  59. This command returns the empty string.  
  60. .TP
  61. \fBblt_watch configure \fIname\fR ?\fIoptions...\fR?
  62. Queries or modifies the configuration options of the watch \fIname\fR.
  63. \fIName\fR is the name of a watch.
  64. \fIOptions\fR may have any of the following values:
  65. .RS
  66. .TP
  67. \fB\-active \fIboolean\fR
  68. Specifies if the watch is active.
  69. By default, watches are active when created.
  70. .TP
  71. \fB\-postcmd \fIstring\fR
  72. Specifies a Tcl procedure to be called after each
  73. Tcl command.  \fIString\fR is name of a Tcl procedure and optionally
  74. any extra arguments to be passed to it.  Five arguments are appended:
  75. 1) the current level 2) the command string 3) a list containing the
  76. command after substitutions and split into words 4) the return code
  77. of the previous Tcl command, and 5) the results of the previous command.
  78. The return status of the postcmd procedure is always ignored.
  79. .TP
  80. \fB\-precmd \fIstring\fR
  81. Specifies a Tcl procedure to be called before each
  82. Tcl command.
  83. \fIString\fR is name of a Tcl procedure and optionally
  84. any extra arguments to be passed to it.  Three arguments are appended:
  85. 1) the current level 2) the command string, and  3) a list containing the
  86. command after substitutions and split into words.
  87. The return status of the precmd procedure is always ignored.
  88. .TP
  89. \fB\-maxlevel \fInumber\fR
  90. Specifies the maximum evaluation depth to watch Tcl commands.
  91. The default maximum level is 10000.
  92. .TP
  93. \fBblt_watch deactivate \fIname\fR 
  94. Deactivates the watch, causing Tcl commands to be no longer traced.
  95. .TP
  96. \fBblt_watch info \fIname\fR 
  97. Returns the configuration information associated with the 
  98. watch \fIname\fR.  \fIName\fR is the name of a watch.
  99. .TP
  100. \fBblt_watch names\fR ?\fIhow\fR?
  101. Lists the names of the watches for a given state.
  102. \fIHow\fR may be one of the following: \fCactive\fR, \fCidle\fR, 
  103. or \fCignore\fR.  If no \fIhow\fR argument is specified all, watches are
  104. listed.
  105. .RE
  106. .PP
  107. If no \fIlevel\fR argument is given, the current level is printed.
  108. .SH EXAMPLE
  109. The following example use \fBblt_watch\fR to trace Tcl commands 
  110. (printing to standard error) both before and after they are executed. 
  111. .DS 
  112. \fC
  113. proc preCmd { level command argv } {
  114.     set name [lindex $argv 0]
  115.     puts stderr "$level $name => $command"
  116. }
  117.  
  118. proc postCmd { level command argv retcode results } {
  119.     set name [lindex $argv 0]
  120.     puts stderr "$level $name => $argv\n<= ($retcode) $results"
  121. }
  122.  
  123. blt_watch create trace \
  124.     -postcmd postCmd -precmd preCmd
  125. \fR
  126. .DE
  127. .SH KEYWORDS
  128. debug
  129.